Welcome to HTML Markup 2.2

the ultimate text-to-html experience

HTML Markup is a fast, effective, economical, and customizable way to put your existing text documents on the World Wide Web. This document will help you use HTML Markup 2.2 more effectively. Online help is available for all menu items and options through Balloon Help. To turn on Balloon Help, select "Show Balloons" from the help menu and point to the item that you would like to know more about. If you are an AppleScript scripter, HTML Markup 2.2 has a scripting dictionary that any script editor should be able to open.

Table of Contents

Introduction

HTML Markup is the easiest and most flexible way to put existing content on the World Wide Web. The story behind it goes something like this. During the summer of 1995, I did some contract HTML work for a company in Rochester, NY called MemoRandom. One of my assignments was to convert several text articles into HTML. I did the first few manually, looking up the ISO equivalents to special characters like á. Then I found a helpful utility called TextToHTML that did much of the conversion for me.

The problem with this solution, however, was that the client didn't like the way the HTML looked and TextToHTML didn't offer much in the way of customizing the way the files looked (note that TextToHTML has now been modified and offers some means of customization). I knew that other people probably faced the same challenges that I had faced with this project, so I began writing HTML Markup.

I was amazed at the amount of feedback I received about the early public betas of HTML Markup 1.0. People sent in dozens of ideas for new features and I implemented as many as I could. When I finally released HTML Markup 1.1 to the world, I was convinced that it was the ultimate tool for converting text to HTML.

Version 2.0 was released in March of 1996. It was incredibly successful and offered many enhancements over earlier versions. Users asked for an easy and standard way to pick the colors of their documents, so I put in color wheels. You suggested that preferences could be saved in sets, so I added those. You wanted more conversion options. You got 'em. More output options. They're in there. Better interface. Better documentation. Visual status indicator. And more. One of the best suggestions that I was unable to implement at the time was AppleScript support. I'm not much of a scripter myself, but various email messages told me how useful HTML Markup could be if it were scriptable. AppleScript support was the major new feature in HTML Markup 2.2. There are some other new features, all of which are described in the version history below.

Flash forward to 1998 and HTML Markup 2.2.1 was released to fix some long-standing bugs and incompatibilities with OS8.

I hope you find that HTML Markup cuts down on the time it takes you to develop a web page. If you find that HTML Markup saves you time and meets your needs, I request that you register HTML Markup 2.2 with me to get even more options.

Installing HTML Markup 2.2

Version 2.0 was distributed with an installer program, but I was told by an Internet archivist that an installer is a waste of space. So instead, I am distributing this version without an installer. To install it, simply copy the HTML Markup folder onto a hard drive. Please note that drag-and-drop features may not work correctly if HTML Markup is running off a floppy disk.

Quick Start

HTML Markup is very easy to get up and running. If you can't wait to get started, here's the quick start:

  1. Launch HTML Markup by double-clicking on the icon
  2. Select the conversions that you would like to apply on the "Job Ticket"
  3. Click "Convert File..."
  4. Select the text file you would like to convert
  5. HTML Markup will convert the file and prompt you for a place to save it

That's all! Five easy steps. Of course, if you want to get more involved, HTML Markups allows you to do a lot more. You can select document colors from a color wheel, add your company's logo as a footer, process hundreds of files in seconds using Drag-and-Drop, and save your settings for future use. Read this document for more information about these and other features. Or simply double-click the icon and start exploring!

A Beginner's Tutorial

To explore some of the features of HTML Markup, we'll follow a hypothetical user through his experience with the program. Our user is named Stanley. Stanley is a student at Standard University and writes articles for the Standard Daily in a weekly column. Stanley's editor has recently told Stanley that he must put his article on the Daily's web site each week. Since his articles are already in text format, Stanley selects HTML Markup 2.2 as his HTML conversion tool.

Since HTML Markup is such an easy program to use and Stanley knows it supports Balloon Help, he launches it to get started right away. The first thing Stanley sees is the friendly HTML Markup Job Ticket:

Fig. 1 - The HTML Markup 2.2 Job Ticket

Stanley goes down the list of options for Titles and Headers and checks off the ones he would like to apply. Since the first line of his article is always the title, he selects "Convert first line to <TITLE>", "Convert first line to <H1>", and "Center first line". These three options together will make the first line of each of Stanley's articles both the title of the Web page and a large header, centered at the top of the page.

Stanley then moves on to Conversion options. Stanley wants his articles to be displayed in a narrow column in web browsers just like it does in the Daily, so he selects "End all lines with break <BR>" to preserve the carriage returns in his file. Stanley recalls that this week's article contains a list of suggestions for things to do on campus. When Stanely wrote the article, he put a single dash before each item on the list. Stanley selects "Convert bulleted/dashed lists <UL>" to tell HTML Markup to convert his text list into a nice, neat HTML list. Stanley decides that these options should be enough to give him a nice-looking page.

Before converting the document, Stanley decides to customize the look of his web page a bit more by using the Preferences. Stanley clicks on the "Preferences..." button to display the preferences window:

Fig. 2 - The HTML Markup 2.2 Preferences Dialog

The Standard Daily doesn't print color pages, but HTML supports hundreds of colors and styles. Stanley wants his pages to look spiffy so he decides to use Standard University colors for his web pages. He wants the text to be cardinal red and the background to be pine green. Stanley clicks on the "BGCOLOR" button to select his background color. He finds pine green on the color wheel and clicks okay. The color tile next to the BGCOLOR is now pine green, showing Stanley how the background will look. Stanley then clicks the "TEXT" button and selects cardinal red from the color wheel as his text color. Again, the tile next to the button reflects this choice.

The Daily is big on copyright issues, so Stanley wants every article to have a copyright line. Stanley enters "Copyright 1996, the Standard Daily" in the "Comment" text field of the preferences dialog. This comment will be included at the beginning of each file, but won't be seen within the web browser.

Finally, Stanley wants the date and time when the article was published to appear at the end of every article, so he selects the "Add date and time" option. Stanley is now done with the preferences so he clicks "OK" and he's back at the job ticket.

Now Stanley is ready to convert his article. He clicks "Convert File..." on the job ticket and selects his text file. A split second later, Stanley is prompted for a place to save the converted article. "Sheesh," says Stanley in amazement, "HTML Markup sure is fast!" Stanley saves the article across the network on the Daily's hard drive and within minutes, the webmaster puts it up on the site.

HTML Markup 2.2 Features

Here's a quick rundown of the features of HTML Markup 2.2. Additional information is provided through balloon help within the program. To turn on balloon help, select "Show Balloons" from the help menu and point to the item in question.

Job Ticket

Sets

Preferences

Output Ticket

Misc. Features

Using HTML Markup Sets - an Introduction

Sets allow you to store different sets of conversion preferences so that they can be used later. Most users find that they are always selecting the same conversion options for their jobs. Rather than to select the same ones each time, these options can be saved in a set named "Default" Each time HTML Markup is launched, it will automatically make the "Default" set active (Note: If you have more than one set named Default, the first one will be selected). If two or more people are using HTML Markup on the same machine to convert files, sets are a great way to store each user's preferences. Sets deal with all aspects of conversion, including document colors, conversion options, output options, and just about everything else. Sets also deal with header and footer files dynamically. This means that the file is read into memory each time the set is selected. So if you use your company's address as a footer and the address changes, all you have to do is change it in the footer file and the next time the set is selected, it will be updated.

Sets are very powerful because it makes HTML Markup an even faster and easier program to use. If you convert several different types of files, you can have a separate set for each type. You should realize, however, that the program was not designed around the concepts of sets. It is a very powerful feature, but it is a very small part of a relatively large program. You can't create more than five sets in the shareware version of HTML Markup 2.2 or seven sets in the registered version. You may find the usage of sets a little difficult to get used to. HTML Markup 2.2 is fully-usable without sets, but I encourage you to play around with them and get used to them. They can be very helpful.

Using HTML Markup Sets - a Tutorial

Let's go back to visit Stanley, our hypothetical journalist for the Standard Daily. We introduced Stanley in the Beginner's Tutorial. If you skipped that part, you might want to go back and quickly skim it.

Let's assume that Stanley has just converted his first article to HTML and he's still in the HTML Markup 2.2 program. He knows that he has several more articles to convert, but he also knows that he has a physics midterm the next day and has to go study. So Stanley decides to save his settings as a set so he can come back and use them later. All he has to do is get to the sets dialog by clicking "Modify Sets..." on the job ticket or selecting it from the File menu. Stanley gets the dialog box we see below:

Fig. 3 - The HTML Markup 2.2 Sets Dialog

Stanley has read a little about HTML Markup 2.2 sets, so he knows what's going on. Right now, he is working in what is known as the "custom" set. The custom set is really just whatever settings are currently active. Usually, if the custom set is active, it means that some modifications have been made to a set and it hasn't been saved yet. However, the custom set is also activated when HTML Markup 2.2 is first launched and when the current set is deleted. But this is all trivial to poor Stanley, who just wants to save his work for tomorrow. He clicks "Save Current Settings as a Set..." and types "Stanley1" as the name of the set. Stanley clicks "OK" to go back to the Job Ticket. He's still in the custom set right now, but he checks the Sets popup menu in the corner of the job ticket and sees that "Stanley1" has indeed been saved as a set. With confidence, Stanley quits HTML Markup 2.2 and goes to study for his exam.

The next day, Stanley aces his physics test. Now, I'm not saying that HTML Markup 2.2 had anything to do with that, but if Stanley had converted his article by hand, how much study time would he have lost? And what if he needed to use a commercial HTML editor to do it and ended up sitting in front of his computer cleaning up the output that it gives?

Anyways, Stanley is looking at his glorious converted web page when he gets a frantic call from his editor. As it turns out, Stanley created a controversy when he converted his article using Standard University's school colors. Half of campus loved the way the colors livened up the article and added bookmarks to it in their web browsers. The other half had trouble reading it with such bright clashing colors and complained to the Daily. While Stanley was taking his midterm, a huge debate was sparked and riots broke out all over campus. Stanley's editor looked to Stanley for a solution and Stanley looked to HTML Markup 2.2.

With the speed of lightning, Stanley launches HTML Markup 2.2. He selects "Stanley1" from the sets menu and all his preferences from the previous day come instantly back. Stanley goes to the preferences window to take a look at the colors he selected. The color tiles allow Stanley to see how bad the colors really look together. Yet they are the school colors and many people like them. Stanley decides to make a compromise. He'll publish two versions of each of his articles. One will be in the school colors and the other will be in the standard HTML colors.

To do this, Stanley unchecks the "Use" button next to the colors. This means that the colors he sees will not be used when the documents are converted. Returning to the job ticket, Stanley notices that the current set is the "Custom" set, implying that a change has been made from the "Stanley1" set. Stanley uses the Sets dialog to save his new settings as "Stanley2".

Now, whenever Stanley wants to convert a group of articles, all he has to do is launch HTML Markup 2.2, select "Stanley1" from the popup menu, select the files in the Finder, drop them onto the HTML Markup icon, then do the same after selecting "Stanley2" from the popup menu. What could be simpler?

By using HTML Markup 2.2 sets, Stanley has successfully cut down his web page development time to almost nothing, saved Standard University from riots and looting, and received a promotion to Assistant Editor of the Standard Daily.

HTML Markup and AppleScript - an Introduction

HTML Markup 2.2 supports scripting through AppleScript (or any other OSA language). While scripting provides a lot of new power to HTML Markup, it is a bit non-standard. HTML Markup 2.2 is my first scriptable application and the first time I've really used AppleScript extensively with any program. Any future versions of HTML Markup will enhance the scriptability to provide a more standard interface and more powerful commands. HTML Markup 2.2 gives you all the basics so that you can script HTML Markup. This section is meant for people who have used AppleScript before. If you haven't, please see the documentation that comes with AppleScript or try the examples below.

The Standard Suite
Like any good program, HTML Markup 2.2 supports the standard suite of commands:

The HTML Markup Suite
HTML Markup has its own suite of commands to extend the standard suite:

HTML Markup and AppleScript - Examples

Support for AppleScript greatly extends the power and flexibility of HTML Markup. If you have any ideas for scripts or actual scripts that use HTML Markup scripting, please let me know. I'd be glad to include them in future versions of HTML Markup either as demos or shareware. I'd also be interested to see what people are doing, even if you don't want me to include it with the program. The examples below start off basic and get a bit more complicated. All of these examples are included with HTML Markup 2.2 in the "Scripts" folder.

Opening Converted Files with Netscape
One of the often-requested features for HTML Markup is the ability to preview the converted file. AppleScript support allows you to do this through a script. This little script will prompt you for a file, convert it with HTML Markup and open it with Netscape. It assumes that the set you switch to saves the file with the same name as the original.

set myFile to (choose file with prompt "Pick a file to convert:")
 tell application "HTML Markup 2.2"
	SwitchSet "Use Same Name"		-- you'll need to create this set
	open myFile
end tell
 tell application "Netscape Navigator™ 3.0"
	open myFile
end tell
 


Converting Files Directly in BBEdit!
This script will let you select text within BBEdit (a popular text and HTML editor) and convert it right within the program! HTML Markup is actually running in the background doing the conversion. Note that this script will not work with BBEdit Lite, since that program is not scriptable. It has been tested with BBEdit 4.0 and probably works with earlier versions, though it may need minor adjustments. To use this script, just drop it into the "BBEdit Scripts" folder in the BBEdit folder. In BBEdit, select the text you want to convert. Then select "BBEdit Markup" from the script menu (the one with the little script icon). You will be prompted for the name of a set to use (just hit return to use the default set). HTML Markup will replace the selected text with valid HTML code! Note that I have also included "BBEdit Simple Markup" in the scripts folder. The Simple Markup script will allow you to convert special characters--yielding HTML equivalents instead of an entire HTML file.

display dialog ¬
	"Which set should I use?" default answer "Default" default button "OK"
set theset to text returned of result
 tell application "BBEdit 4.0"
	set thesource to selected text of window 1
	tell application "HTML Markup 2.2"
		SwitchSet theset
		set theresult to ConvertText thesource
	end tell
	insert text theresult
end tell
 


Setting up a "Watch File"
This is a pretty clever script that demonstrates some really useful ways of scripting HTML Markup. This purpose of this script is to wait until a particular file appears in a particular folder. This file is then converted and saved in the folder that the web server is in. This script would be used if, for example, you are on a network and want other people on the network to be able to post files to the web server. Make a drop box that they toss a text file into and HTML Markup will immediately find the file, convert it, and save the converted file in the web server's folder. This script is important because it shows one way to convert files that appear when you're not around and also because it shows how to save files in folders other than the folder the source file was in.

set source_file to "Macintosh HD:Convert Me"
set dest_file to "Macintosh HD:WebStar:Convert Me.html"
 repeat
  tell application "Finder"
    if (file source_file exists) and not (file dest_file exists) then
      tell application "HTML Markup 2.2"
        set theResult to Convert file source_file
        open for access file dest_file with write permission
        write theResult to file dest_file
        close access file dest_file
      end tell
    end if
  end tell
end repeat


Serving up documents on the fly
If you have several hundred text files on your server and you want to make the same files available as HTML as well, you could convert them all and put them in the web server's folder, or you could just have HTML Markup convert the files as needed! Doing this involves using HTML Markup as part of a CGI script. The following script comes with help from Jon Wiederspan's excellent book "Planning and Managing Web Sites on the Macintosh". I highly recommend this book. This particular script works by using an HTML form that has a popup menu of files. The appropriate file is converted and displayed based on which files is selected from the menu. It can be customized to work with other types or forms or plain links. Note that it also requires the ACME OSAXen, which are available online.

property crlf : (ASCII character 13) & (ASCII character 10)
property http_10_header : "HTTP/1.0 200 OK" & crlf ¬
	& "Server: NetPresenz" & crlf ¬
	& "MIME-Version: 1.0" & crlf ¬
	& "Content-type: text/html" & crlf & crlf
 on «event WWWΩsdoc» path_args ¬
	given «class kfor»:http_search_args, «class post»:post_args
	set formData to ACME parse args post_args
	set source_file to ACME lookup field "file" in formData
	if source_file = "file 1" then
		tell application "HTML Markup 2.2"
			set mystring to Convert file "Macintosh HD:file 1"
		end tell
	else if source_file = "file 2" then
		tell application "HTML Markup 2.2"
			set mystring to Convert file "Macintosh HD:file 2"
		end tell
	end if
	return http_10_header & ¬
		mystring
end «event WWWΩsdoc»
 

Other scripts and CGI's are available in the "Scripts" folder that came with HTML Markup 2.2. If you have any ideas for scripts or actual scripts, please send them to klephacks@kagi.com

The Made with HTML Markup Program

If you use HTML Markup on your site and want to help me out, please display this icon and link to http://www.printerport.com/klephacks/

Common Problems Experienced

I drag a file onto the HTML Markup icon and nothing happens!

There are two likely reasons why this is happening. Both are pretty simple to fix. The first possibility is that the file you are trying to convert was not saved as a plain text file. HTML Markup only works on plain text files! If your file was written in a word processor like Microsoft Word, open it back up and save it again, this time as "plain text"

The second possibility is that your desktop file needs to be rebuilt. The desktop file is an invisible file on your hard drive that tells the computer which programs can open which files. If the desktop file isn't rebuild once and a while, the computer gets a bit confused. To rebuild your desktop file, restart your computer. When you're almost at the desktop, hold down the command and option keys. The Mac will ask you if you want to rebuild your desktop file. You do, so click OK.

There's actually a third case, but it's very rare. Sometimes the desktop file gets corrupted and even rebuilding it doesn't do the trick. In this case, you have to make this invisible file visible and then throw it in the trash. You can use ResEdit to do it, but if you've never used ResEdit before, I wouldn't recommend it. Please contact me if the first two solutions don't work.


It won't let me save my settings as a set!

A few possibilities here. What's probably happening is that you already have five sets (or seven in the registered version). This is easy to fix, but you'll lose your current settings. Just select one of the sets that you don't use too often. Go to the Modify Sets dialog and click "Remove Current Set". That set is gone and now you can put all your settings back the way they were and save it as the fifth set. If you need more than five sets, I suggest that you upgrade to the registered version of HTML Markup 2.2 for $20.

Other possibilities are that the preferences file has somehow become corrupted or HTML Markup is dangerously low on memory. Try removing the "HTML Markup Preferences" file from the preferences folder within your system folder. You'll lose your saved sets, but a new prefs file will automatically be created. If it's a memory problem, try giving HTML Markup 2.2 more memory by highlighting it and selecting "Get Info" from the File menu in the Finder.


HTML Markup tells me it's out of memory, but it doesn't seem to be

Many programs take a simple approach to memory which is basically, if there's not enough memory to do something, the program tells the user and the program quits. HTML Markup doesn't work this way. If you try to do something, and there's not enough memory, HTML Markup will tell you that there's not enough memory and simply won't do it! You can keep on working just as you would otherwise, but whichever feature you selected won't work. For example, if HTML Markup only has 10k free and you include a 200k header file, HTML Markup will tell you that there's not enough memory to load the header file. However, you will still be able to use your other options and convert your files without appending the header. Please note that if you did want to use the header in question, you can very easily give HTML Markup more memory by quitting, getting info on HTML Markup and giving it as much memory as you want.


I try feature x and it tells me that it's not available in this version

There are two versions of HTML Markup 2.2. The one you are using is the shareware version, which means that you have not paid for it. This version is fully-working and has most of the features of the registered version. However, for a small fee, you can pay for this software and receive the registered version, which will allow you to take advantage of the feature you are attempting to use. See the Registration Section for more details.


A particular portion of my file was left out or converted improperly

HTML Markup 2.2 has been through an extensive beta period and we believe it to be a very strong and capable program. However, there is the chance that something has slipped by and maybe you have the one in a million file that HTML Markup can't handle correctly. If HTML Markup doesn't convert your file the way that it should, please send the file to me at klephacks@kagi.com and I'll take a look at it. Please send the file as a MIME attachment if you can.

Questions and Answers

Q: Who are you?

A: My name is Scott J. Kleper. I'm a sophomore at Stanford University, originally from Pittsford, New York. I'm 19 years old and I've been programming Macs for about four years. I've been writing shareware for almost as long. My other programs include MacFolklore, HTML Markdown, Jot, and PowerSpaceTabsPlus. All are available from the KlepHacks web page at http://www.printerport.com/klephacks/


Q: Why did you write HTML Markup?

A: During the summer of '95, I did some contract work for a web consulting firm. My first assignment was to convert several articles from text to HTML. I used a freeware program to do it, but the output was a mess and there were no options to select from. I began to write HTML Markup for future projects and quickly realized that it was a general purpose utility that anybody could use. Versions 1.x were all modal programs, meaning you couldn't switch to the finder and they operated linearly. I designed it this way because it was mainly for my own use. However, as it caught on, people started suggesting tons of new features. I wrote version 2.0 from the ground up, incorporating many of your ideas. Version 2.2 fixes some bugs, and adds AppleScript support and a few other niceties.


Q: Aren't there other similar programs?

A: Yes, there are several other programs that do similar tasks. When I first had to convert text to HTML, I used TextToHTML, a freeware program. It was fast, but had few features and wasn't very customizable. There's a relatively new one called Hyperize, which is similar to TextToHTML. Hyperize seems to do pretty well with links, something that HTML Markup admittedly falls a bit short on. However, Hyperize is also difficult to customize and doesn't have nearly as many features as HTML Markup 2.2. I've talked to both authors of these programs. Both are really nice guys and I encourage you to give their programs a shot too and use whichever is best for you.


Q: What about Adobe's PageMill?

A: I was a big fan of PageMill when I first saw it and seriously considered abandoning HTML Markup since PageMill looked so great. But they're really two totally different things. PageMill is an editor and HTML Markup is a processor/converter. PageMill also has some serious problems. The output is very messy and the program is a bit buggy. I don't consider PageMill to be a competitor, and if you're doing basic web design from scratch, you might want to give it a try, but if you're doing serious conversion of existing content, HTML Markup is probably the way to go. I've also recently seen some betas of various editors that are on the horizon. They seem to have come a long way, but none of them offer conversion of existing documents, which is what HTML Markup does and does well.


Q: Where's support for new HTML stuff like tables and client-side imagemaps?

A: I may include support for some of the newer HTML flags in future versions. However, I consider HTML Markup to be primarily just a text to HTML converter, and things like tables are probably beyond the scope of the program. There are some existing converts available for converting tab-delimeted text files and Excel spreadsheets into HTML tables. Check the info-mac mirrors in /text/html/


Q: Where's support for new Apple technologies?

A: One of the most requested features has been AppleScript support. Scripting is now possible with HTML Markup 2.2 (see above). As far as other technologies are concerned, if there's something you want to see, send me the idea and I'll see what I can do. Send email to klephacks@kagi.com


Q: I work for a user group, CD-ROM publisher, or magazine. Can we give out your program?

A: If you're going to be distributing it electronically or on disk, you may distribute HTML Markup without notifying me. However, I still request that you send me a quick note letting me know where it's going to be distributed. If you are going to write an article or review of HTML Markup, I really really really want to read it. Please please please send me a copy of the article. If you're going to be distributing HTML Markup 2.2 on a CD-ROM, you must notify me first. I will generally grant permission for distribution, but I want to know which CD it's going to be on. Send permission requests, reviews, etc. to:

Scott J. Kleper
Attn: HTML Markup 2.2
klephacks@kagi.com
134 Caversham Woods
Pittsford, NY 14534-2834
USA


Q: I want to learn more about HTML in general. Where can I look?

A: I learned HTML mainly from online resources. I'd check www.yahoo.com for resources. If you'd prefer a book, I'd recommend "Internet Power Web" by Pacific HiTech for a very quick and basic introduction to web publishing.


Q: Why does this splash screen come up randomly? Just to annoy me into giving you money?

A: It's not to annoy you at all. The splash screen comes up at random. It will show up the first time you run HTML Markup and there's about a one in ten chance every subsequent time. It's not meant to disturb you, just to remind you that you are using a shareware program that I put a lot of work into and I would really appreciate it if you would help me out by paying your shareware fee.


Q: Is HTML Markup really that much faster since it's PowerPC native?

A: Nope, not really. It's interesting and I've done many tests to find out exactly how much faster the PowerPC version is. Basically, if you're running Speed Doubler anyways, HTML Markup 2.2 runs at about the same speed regardless of whether you run the 68k version in emulation or the native PowerPC version. The difference shows up when you start converting hundreds of files or complex files. When you start to get up in that range, the PowerPC version is up to 200% faster (or more). The reason is because the real factor that slows down conversion is saving and opening the files. The File Manager isn't PowerPC native yet, so it's still slow regardless of whether or not the program is native. So there's some speed boost, but it's not always obvious.


Q: What's going to happen to HTML Markup in the future?

A: There are lots of features that I'd like to include. I probably won't start the next version right away, unless there are bug fixes to do. But please continue to send me ideas and I'll do what I can to include the features you want in future version of HTML Markup. There are three possibilities for future development. I may concentrate on some of my other projects like NetBots and not work on HTML Markup for a while. I might continually modify version 2.2, adding new features, or I might start a new version from scratch that would make the program more powerful and flexible.


Q: Why can't HTML Markup recognize and convert styled text and graphics?

A: HTML Markup is a text converter, and text can't contain styles and graphics! The ability to use styles and graphics is something people have been asking for for a long time. There are some other converters that recognize formats like RTF, which can contain styles. A future version of HTML Markup may add support for RTF or another styled format, but I can't make any promises.


Q: What's the point of a text-to-HTML converter? Isn't HTML already text?

A: HTML is a format that contains plain text. However, HTML offers much more than plain ASCII text does. HTML offers links, styles, lists, lines, and much more. Text is an extremely popular format and is the lowest common denomenator for all operating systems. Millions of documents already exist in text format. HTML Markup provides an easy and effective way of putting these documents online and taking advantage of many of the features that HTML offers.


Q: Can I have the source code so I can write my own converter?

A: No. HTML Markup 2.2 is a copyrighted product and I will not release the source code. However, I am sympathetic towards other people working on similar projects and I'd be happy to discuss techniques or provide help with your program. Send me email.

Registering HTML Markup

Writing shareware is a lot of work, especially for a college student. Considering all the time that HTML Markup can save you, I request that if you find it useful, you pay your shareware fee.

If you do decide to register HTML Markup, you will receive the registered version, which will give you access to all the "locked features" that you can't use in the shareware version. It will also allow you to disable the credit lines at the end of each document and to store up to seven sets (and give you three new presets).

Registration costs $15 for a single-user license. This means that one person can use HTML Markup 2.2 on one Macintosh. If you're in a multi-user environment, or want to have HTML Markup 2.2 installed on multiple machines, you may purchase multiple licenses at $15 each or a site license for $400. If you are a registered user of HTML Markup 1.0 or HTML Markup 1.1, you may upgrade to version 2.2 for $5. If you are a registered user of version 2.0 or later, you are entitled to a free upgrade to 2.2.1. Send me email and I'll email you the update. If you decide to upgrade, you must do so directly through me.

The prefered way of registering is to send me a check directly. Make your $15 check payable to Scott J. Kleper and please include your email address if possible. I can also take traveler's cheques, money orders, and international money orders in US dollars.
Send checks to:

Scott J. Kleper
Attn: HTML Markup 2.2
134 Caversham Woods
Pittsford, NY 14534-2834
USA

The alternate way of paying is through the Kagi shareware payment service. Paying through Kagi allows you to use a check, credit card, or electronic payment. To register through Kagi, just double-click the "Register KlepHacks" program that came with HTML Markup 2.2. If you didn't get the Register program when you downloaded it, it is available from:

http://www.printerport.com/klephacks/downloads.html

Again, please include your email address so that I can send the registered version to you as quickly as possible.

Kagi also now offers a way to register electronically through the web. More information is available at http://www.printerport.com/klephacks/sales.html

One last thing about registering. I really appreciate it when people send comments about and suggestions for the program. I read them all and often use the feedback for future versions. If you use the Kagi method, you can still send comments.

About the Author

I'm currently a junior Computer Science student at Stanford University. I've been using the Macintosh since 1984, when I was just tall enough to reach the keyboard and just curious enough to wonder why the screen wasn't color like all other computers. I started programming in BASIC when I was in third grade and I've never quite gotten over it. Sometimes I have nightmares about GOTO's. When I was a freshman in high school, I got my first Mac of my very own, an LC. I dug up an old copy of Microsoft BASIC for Macintosh, a terrible implementation of a terrible language. I still wanted to program Macs though, so I took a few classes in Pascal at the Rochester Institute of Technology when I was a sophomore in high school. I came to Stanford for a summer program in 1993, where I learned how to program in C. At about the same time, I started reading Mac programming books to learn some of the toolbox calls. My first programs were pretty bad. I hacked together a really pathetic paint program in a few weeks and called it ScottPaint. I started a game after that was called Reality Sucks, but never got very far with it. My first real Macintosh program was actually begun as an attempt to learn how to display text and receive input from users for Reality Sucks. I put together a little text editor with the old-style TextEdit records (assuming falsely that they'd be easier to learn) and gradually added features to it. That project became known as Jot, which I worked on for about a year. During my senior year in high school, I wrote a bunch of little programs like HTML Markdown, which converts HTML into text, PowerSpaceTabsPlus, which converts strings of spaces into a single tab, and MacFolklore, which quizzes you on the history of the Macintosh. During the summer of '95, I did some contract work with HTML and wrote HTML Markup as a way of automating really repetitive conversion tasks. Since HTML Markup has been available, I've written several other programs including NetBots and KlepSig. All of these programs are available from the KlepHacks web site. Versions 1.0, 1.1, and 2.0 of HTML Markup were all very successful. Each consecutive version is the result of listening and reacting to user feedback. HTML Markup 2.2 has the features that users asked for and I know it will be a success.

If you have any questions, feel free to send me mail at klephacks@kagi.com

Special Thanks

Many people have helped me with this project and I'd like to take this opportunity to thank as many of them as I can think of. I'd like to thank my dad, Michael Kleper, for raising me on Macs instead of PCs. I'd like to thank Randy Stahl for getting me started with Mac programming. I'd like to thank all the users of HTML Markup for sending in suggestions and registering the program.

This program has gone through a rather extensive beta testing period by a small number of dedicated beta users. Each have contributed a lot to the program. The interface you see was developed by myself with a lot of help from Darien Kruss. Some of the graphics were done by Dave Laster, including the about box. A lot of the features were suggested by Matt Garlinghouse and Luke McCormick. Just about everybody contributed something to the program you now have installed. Here are the names of the beta testers:

I'd also like to thank my mom. Thanks, mom!

Version HIstory

HTML Markup ALPHA versions (5/9/95)

The alphas implemented some of the basic filters like use first line as <TITLE>. They had a 3 meg memory partition for safety because they had no solid memory management technique. Unlike more recent versions, they did not estimate the size of files and allocate memory appropriately. Instead, they used the formula of adding a small buffer to the size of the original file. It worked surprisingly well and was fast, but unpredictable for situations where the formula didn't work. Very little of the ISO 8859-1 character set was implemented so while some characters like < and > would be converted, other international characters would not. These versions expired on 6/1/95.

HTML Markup 1.0b1 (5/11/95)

Version 1.0b1 was almost identical to 1.0a2. There were some minor bug fixes, interface changes, and documentation changes. This version expired on 6/1/95.

HTML Markup 1.0b2 (5/22/95)

Version 1.0b2 fixed a few minor bugs. The biggest change was that it was the first PowerPC-native version of HTML Markup. Version 1.0b2 was distributed as a fat binary application. Speed improvements on the PowerPC were only about 15% with a large number of files. I attribute this to the fact that the file system is not native, so in theory Copland should bring a big speedup.

HTML Markup 1.0b3 (6/3/95)

Version 1.0b3 fixed a few minor bugs, once again. There was a problem with memory allocation that caused the shareware message to appear more than once in the output. Also, words separated by a carriage return were squished together. This was fixed. The memory allocation algorithm was modified to double the size of the original file and then add a 10k buffer, making it safer but still unpedictable in strange circumstances and incredibly inefficient for others.

HTML Markup 1.0b4 (6/24/95)

Version 1.0b4 was the first really stable and powerful version. On the technical side, it implemented an all new estimation algorithm to replace the old memory allocation algorithm. This new technique would run through the conversion twice. The first time, it would figure out how much memory it needed for the output file. The second time, it would actually write the file. I added more escape code conversions, implementing all the essentials from the ISO 8859-1 character set. I added a "smart list" algorithm that replaced the old list conversion function. With the old algorithm, any word with a dash in it would be converted into a list. The new one only treats lines that start with a dash as list items. Version 1.0b4 introduced the output ticket button. The output ticket combined all the output options from the main job ticket with a few extras like add .html to the name, and setting the creator code. Two new options on the main job ticket allowed converting dashed lines to <HR> flags and keeping inline HTML flags.

HTML Markup 1.0b5 (7/24/95)

The output ticket now allowed you to convert spaces in the names of output files into underscores and/or convert the file names to lower case. If you were a paid user of HTML Markup, you received instructions on how to enable the registered features. You could automatically convert any standard URL's in your document into clickable links in version 1.0b5. A new option turned lines beginning with # (pound sign) characters into items of an <OL> (numbered list). A new option created an index.html file with links to all of the files that Markup created. You could now have two-level lists. If you simply indent a list within another, Markup would make it into a nested <UL>. The job ticket was rearranged so it would fit on smaller screens and have some sort of order to it. A dialog box was added that tells users how to properly run HTML Markup when the double click the icon instead of dropping files on it. I set default items for all of the dialog boxes to "ok". As the conversion algorithms for Markup grew more and more complex, I began to wonder if the algorithm that estimates the final file size would hold up. It appears that it did, but just to be sure, I increased the buffer size from 500 bytes to 5 kilobytes. If you used the add .html option in 1.0b4, there would be problems with files that already had long times. Markup will now truncate it. Pressing cancel on the job ticket will now quit immediately instead of showing the final report. In fact, the button has been renamed "quit". If the end part of your source file was a list and you had Markup convert lists to <UL>'s, it would cause the shareware message to be indented because the list was never ended. Markup will now end all lists at the end of the file. If you had special characters in the title of your document, they would not be converted to the proper codes in earlier versions. They now will.

HTML Markup 1.0 (8/1/95)

For the registered version, there is now a popup menu that allows you to select the colors. Previously, you had to know the RGB values. There is a tradeoff though. With this method, you only have a selection of 11 colors. There is also a popup menu in the output dialog for selecting the file creator. You can still enter it manually, but you can also choose from Netscape, BBEdit, Microsoft Word, Jot, or SimpleText. I added <BR> tags to the index.html file. A bug in earlier versions caused all the links to be on one line! One user reported that he used URL's within sentences and when Markup converted them to links, it included the trailing periods. I recommend that you always enclose your URL's with < and > but if you use them in sentences, Markup will now recongnize that and treat it appropriately (i.e. it will ignore the period). I got rid of some extra \r (carriage returns) that I had originally put in for debugging purposes. This makes the output look nicer, especially for lists, embedded lists, and numbered lists. I also added support for two more required AppleEvents, namely OpenApp and QuitApp. It's pretty pointless to add PrintDoc because Markup can't print anyways.

HTML Markup 1.1 (8/13/95)

Version 1.1 fixes several small bugs. One problem encountered by a few users with some interesting memory configurations was a write to NIL problem with the summary dialog. A temporary fix for those still using 1.0 is to simply uncheck the "Show final summary" option on the job ticket. Somehow, conversion of smart quotes was _disabled_ in version 1.0 of HTML Markup (it worked fine in the betas). I reenabled it in version 1.1. I also implemented the full ISO Latin set. Now just about any international character or symbol can be converted. There are some symbols, however, that are not in the ISO set so they may not display properly. Where necessary, I have built in my own conversions. I also increased the buffer size of HTML Markup from five kilobytes to seven kilobytes. This really doesn't affect the user. There were no problems with the 5k buffer, but I feel safer with the extra 2 kilobytes. As a side-note, HTML Markup 2.x uses an exact estimation technique so it will not require any buffer at all.

HTML Markup 1.1.1R (11/22/95)

Version 1.1.1R fixes a small bug that showed up ONLY in the REGISTERED version of HTML Markup 1.1. The bug showed up when the "show final summary" option was selected. HTML Markup would convert the documents without a problem but would then crash without showing the summary. This problem was caused by a renumbering of resources in the summary dialog.

HTML Markup 2.0 (3/1/96)

Version 2.0 is a total rewrite of the original program with tons of new features and a flashy new interface. The key features are that this version is non-modal, meaning that you can switch from HTML Markup to the Finder. Previous versions were modal and linear. You launched the program, did your conversion, and it quit. Now you can leave HTML Markup running. Version 2.0 has a great new feature called "sets" that allows you to store multiple settings for different types of jobs. You can select the set you want to use from a popup menu. There are several new conversion options, including nested list conversion of more levels, different styles of line conversions, converting the file name to the title, adding the date and time of the conversion, and much more. Selecting colors is now much better. Instead of selecting from a popup menu, you can now use the standard color wheel to select your colors. You can also now include a URL for the background pattern. The new version is faster. The code is more compact and will allow for future modifications. It is also much more efficient. No estimation of memory allocation is done. Instead, the algorithm is actually run through twice. The first time it figures out how much memory it needs. Yeah yeah, I know this makes it O(2N) for all you CS majors, but the time required is actually negligible in most cases, and it's a very efficient solution. The style of the output is much nicer than previous versions. There's a great new interface with kind of a 3-D look. There's also online help available through balloon help.

HTML Markup 2.0.1 (3/21/96)

Version 2.0.1 fixes a few minor bugs in the initial release of version 2.0. The most significant bug caused bombs on most Macs that did not have Drag-and-Drop installed. While HTML Markup 2.0 was tested on Macs without this handly little extension (built into System 7.5 and later), not all Macs were able to handle its absense and crashed after displaying the splash screen. HTML Markup now checks to see if Drag-and-Drop is installed and doesn't load the code if it's not there. A bug with the "Append credit line" item was also fixed. In 2.0, you could feasibly disable that feature through some clever hacking. 2.0.1 also prevents the user from switching to background windows by clicking in the title bars. For example, the preferences window is a movable modeless window, so you shouldn't be able to switch back to the Job Ticket from there.

HTML Markup 2.2 (8/18/96)

Version 2.2 fixes one conversion bug that falsely translated êto â. It also fixes a bug that caused HTML Markup to crash if you attempted to convert a file that was open from another application. Version 2.2 adds AppleScript support (see above), changes the way paragraphs were defined (paragraphs can now either be separated by a blank line or start with an indented line), and has a few minor interface tweaks.

HTML Markup 2.2.1 (5/6/98)

After a long hiatus, version 2.2.1 was released to fix some long-standing bugs and some new ones that came up with Mac OS 8. One new feature was added-"End all lines with paragraph" and the header/footer features of the registered version were rewritten. Some extra sample sets were added to the shareware version, the price was lowered to $15 and the following bugs were fixed: the color picker now works under OS8, converting all caps to headers now handles lines with 0's in them, header files shouldn't be truncated anymore, and custom sets shouldn't randomly disappear anymore.

Legal Stuff

HTML Markup 2.2.1 is ©copyright 1998, by Scott J. Kleper. You may copy and distribute the SHAREWARE version of HTML Markup 2.2.1 as long as you include all the documentation and everything that came with it when you downloaded it. This program is shareware. If you use it, you are obligated to pay for it. See above for payment/registration information.

No warranty is included with this program. Use it at your own risk. There are no known bugs with this program. However, the author is not responsible for any problems caused by it.

This program may be included in online file areas and archives. It may be distributed through user groups and shared with other users. CD-ROM publishers MUST contact me at klephacks@kagi.com before including HTML Markup 2.2.1 on a CD-ROM product.

If you would like to review HTML Markup for an online or print magazine, please contact me so that I can see a copy.